package edu.gmu.streams;

import java.io.IOException;

/**
 * A BlockInputStream reads primitive Java numbers
 * and characters to an input stream.  Byte order is determined
 * by the particular implementation.
 * <p>
 * This interface differs from DataInput in that it also
 * provides efficient methods for reading primitive arrays in.
 *
 * @author  James H. Pope
 * @version $Revision:$ $Date:$
 */
public interface BlockInputStream //extends FilterInputStream
{
    /**
     * Skips the number of bytes ahead as indicated.
     * @param num bytes to skip
     */
    public void skipBytes(int skip) throws IOException;
    
    /**
     * Reads byte from underlying stream.
     * @return b
     * @throws java.io.IOException
     */
    public byte readByte() throws IOException;
    
    /**
     * Reads boolean (1-byte) from underlying stream.
     * @return
     * @throws java.io.IOException
     */
    public boolean readBoolean() throws IOException;
    
    /**
     * Reads the next two bytes from underlying stream as an short.
     * @return short
     * @throws java.io.IOException
     */
    public short readShort() throws IOException;
    
    /**
     * Reads the next four bytes from underlying stream as an int.
     * @return int
     * @throws java.io.IOException
     */
    public int readInt() throws IOException;
    
    /**
     * Reads the next eight bytes from underlying stream as a long.
     * @return long
     * @throws java.io.IOException
     */
    public long readLong() throws IOException;
    
    /**
     * Reads the next four bytes from underlying stream as a float.
     * @return float
     * @throws java.io.IOException
     */
    public float readFloat() throws IOException;
    
    /**
     * Reads the next eight bytes from underlying stream as a double.
     * @return double
     * @throws java.io.IOException
     */
    public double readDouble() throws IOException;
    
    /**
     * Reads variable length (2-byte length header) of UTF characters from
     * the underlying stream as a String. 
     * @return String
     * @throws java.io.IOException
     */
    public String readUTF() throws IOException;
    
    
    /**
     * Bulk transfers bytes from this buffer into the given destination array.
     * @param bytes
     * @throws java.io.IOException
     */
    public void read( byte[] bytes ) throws IOException;
    
    /**
     * Bulk transfers bools from this buffer into the given destination array.
     * Implemenations may fall back to loop-calling readBoolean().
     * @param booleans
     * @throws java.io.IOException
     */
    public void read( boolean[] booleans ) throws IOException;
    
    /**
     * Bulk transfers shorts from this buffer into the given destination array.
     * @param shorts
     * @throws java.io.IOException
     */
    public void read( short[] shorts ) throws IOException;
    
    /**
     * Bulk transfers ints from this buffer into the given destination array.
     * @param integers
     * @throws java.io.IOException
     */
    public void read( int[] integers ) throws IOException;
  
    /**
     * Bulk transfers floats from this buffer into the given destination array.
     * @param floats
     * @throws java.io.IOException
     */
    public void read( float[] floats ) throws IOException;
    
    /**
     * Bulk transfers longs from this buffer into the given destination array.
     * @param longs
     * @throws java.io.IOException
     */
    public void read( long[] longs ) throws IOException;
    
    /**
     * Bulk transfers doubles from this buffer into the given destination array.
     * @param doubles
     * @throws java.io.IOException
     */
    public void read( double[] doubles ) throws IOException;
    
    /**
     * Bulk transfers String from this buffer into the given destination array.
     * Implemenations may fall back to loop-calling readUTF().
     * @param strings
     * @throws java.io.IOException
     */
    public void read( String[] strings ) throws IOException;
}
